fix(plugin-approvals, service-automation): report a repairable strand, a dropped snapshot and a cascade-failed run apart — through a read-only engine member, not the wire (#15358 B′) - #16704

Fixes #15358

Ruling implemented: B′ (director seat, decision batch #76, 2026-09-07T08:28Z, comment 5567692623; maintainer reply verbatim 「同意」). The discriminator is published as a dedicated read-only engine member, declared on ApprovalResumeSurface the way listSuspendedRunsDurable already is. The wire surface is untouched: no new key on ExecutionLogEntry, no packages/spec change, nothing added to GET /automation/:name/runs/:runId (PIN 3 of the reproduction now pins that). Reproduction base: #16459 (merged) — its PIN 1 went red on this tree and was flipped to the resolved expectation.

The defect

ApprovalService.classifyStrandedRunState keyed on run.status === 'failed'. A cascade-failed run — an ancestor failAncestors failed while parked at its subflow node, whose pause failSuspendedRun consumed and journalled nothing — has the same terminal failed row as the #13909 strand, so the inspection reported both as runState: 'failed' while restoreConsumedSuspension re-arms one and refuses the other (NO_CONSUMED_SUSPENSION). Open instance: #15222 remains open and is the first consumer.

What landed

@objectstack/service-automation (engine.ts, index.ts)

• AutomationEngine.inspectConsumedSuspension(runId) — read-only. Answers from the SAME two witnesses restoreConsumedSuspension reads (this process's hot journal vs the durable row; rowSupersedesJournal, persisted, drop notice). The two-witness read is now one private method, resolveConsumedSuspensionWitnesses, called by both verbs, so they cannot disagree. The restore verb keeps the same decision table (its stale-hot-copy drop is now driven by the helper's staleHot flag) with one instant moved: the hot copy is now sampled after the loadTerminal await rather than before it, so a journal eviction (MAX_CONSUMED_SUSPENSIONS) landing during that await answers a refusal where the old read restored from the copy it had already captured — direction is refusal, never a double-run (the helper's TSDoc says so; contract-review item 1). Not a naive single loadTerminal read — ruling item 2 — and the ablation below shows the pins catch exactly that regression.
• Answers, none folded: repairable: true (+ flowName / nodeId / correlation / witness / consumedAt), SNAPSHOT_DROPPED (+ the drop notice), NO_CONSUMED_SUSPENSION (cascade-failed, never paused, or a snapshot no longer held — the verb does not say which), RUN_SUSPENDED (+ nodeId). REJECTS when a store read fails — same posture as hasSuspendedRun. It re-arms nothing and writes nothing; its one incidental mutation is the strict suspension read's own phantom-entry eviction (service-automation: two loose ends on the #14333 claim path — the loser's hot-cache entry is never evicted, and the 'unsupported' branch answers only after its conditional delete has already been issued #15832, suspendedRuns only, never the journal) — identical to hasSuspendedRun (review item 7).
• ConsumedSuspensionInspection exported from the barrel, for the same reason SuspensionRestoreResult is.

@objectstack/plugin-approvals (approval-service.ts)

• ApprovalResumeSurface.inspectConsumedSuspension?(runId) — optional, declaring a method the engine already implements; widens no engine surface.
• StrandedRunState — the three report members, none folded, with 'missing' untouched: 'repairable' (service-automation: a resume consumes the pause BEFORE running downstream nodes, so any node that throws leaves the run terminally unresumable — and the only inspector for it reports all clear #13909 strand), 'snapshot_dropped' (its own class — as repairable it over-reports, as unrepairable it is a false negative), 'unrepairable' (cascade-failed / never paused / snapshot no longer held, service-automation: restoreConsumedSuspension cannot reach a nested run — a stranded child's cascade-failed ancestors are consumed without a snapshot, so restoring the child continues into a dead parent #15222's shape among them — the label is faithful to the verb: nothing re-arms it; review item 6). 'failed' stays a member on purpose — see fail-closed below.
• inspectStrandedRequests asks the third oracle for failed rows only (pinned: exactly one read, for exactly the failed-and-not-suspended row). The summary log adds runRepairable / runSnapshotDropped / runUnrepairable.

Fail-closed on absence — the load-bearing property

Absence of the discriminator is NOT read as "not a strand". A surface that lacks inspectConsumedSuspension leaves a failed row reported as today's undifferentiated 'failed' — never 'unrepairable' (that calls the repairable row dead: the #15555 false-negative harm one surface over), never skipped (that hides the row) — exactly the ruling's item 1 fallback. A thrown read counts undetermined, like the other two oracles. Pinned twice: on the real engine (stranded-run-repairability.test.ts PIN 5 — the same two rows through a surface carrying only the two older oracles come back ['failed', 'failed']; re-attaching the full surface restores the split, as the positive control) and on a scripted surface (stranded-request-inspection.test.ts, the #15358 block: absent member, thrown read, unknown reason word, RUN_SUSPENDED skip, only-asked-for-failed-rows call count). An answer word this build does not know also stays 'failed'.

The two PM readings re-measured, with controls

Both readings in the dispatch (comment 5572530604, from 5568565582) were false at every tree measured — bc0ac1d1f (this branch's base), 8341ed21c (the base the dispatch named), and origin/main at ba5284e60:

1. "consumedSuspensionDropped has zero hits repo-wide (no producer, no consumer, no test)". Measured git grep -n consumedSuspensionDropped → 18 hits in 7 files: declared on RunRecord (engine.ts:1331), produced by suspended-run-store.ts:796 (readConsumedSuspensionDropNotice), consumed by restoreConsumedSuspension (engine.ts drop-notice arm), tested in stranded-run-object-store.test.ts:297-300, exported type ConsumedSuspensionDropNotice in index.ts. Introduced by 5964124dd (feat(automation): stamp status: 'stranded' on the resume catch arm and pin the re-armed run's exactly-once — the #13937 services half (shape 4) #15237). Positive control: consumedSuspension → 29 hits in engine.ts alone. At 8341ed21c: git grep -c consumedSuspensionDropped 8341ed21c -- packages → 6 files.
2. "The sentence quoted as the engine's own words is written in no file". git grep 'was not a strand' → 0 hits, but only because the sentence wraps: engine.ts:1323-1325 reads "a terminal record with neither field is a run that reached a terminal state which was not [newline] a strand (completed, cancelled, cascade-failed), or never paused at all." The sentence exists; the single-line grep was defeated by the line break.

Consequence, executed under the ruling's own words rather than the dispatch's reading of them: no field was built (the ruling's "one member" is the engine member, and there is one), but the existing consumedSuspensionDropped field is READ — ruling item 3 requires the snapshot-dropped class as its own member, and folding it either way is named there as the wrong shape. The contract review (PASS, zero blocking findings) judged the five-member StrandedRunState CONFORMS to the ruling's verbatim text.

Prose-only patch round (contract review items 1, 6, 7) — commit 42ce7bf4d

Three TSDoc edits and this body; no executable line changed, so the PASS against 1b4dad617 carries across. Proof: git diff 1b4dad617..HEAD -- '*.ts' → 36 changed lines, of which 0 are non-comment lines (every changed line, after stripping the sign and indentation, begins with a comment token); git diff --stat = approval-service.ts +7/−2, engine.ts +24/−3. Typecheck of both packages re-run green on the patch (check:test-typecheck: OK each; the plugin ledger unchanged). Review item 4 (refineFailedRunState running outside the try) is a behaviour change and is deliberately left exactly as it is, for the follow-up card.

Verification (all on 1b4dad617, this branch's head at review = merge of origin/main ba5284e60; the later 42ce7bf4d changes comment lines only)

• pnpm --filter @objectstack/service-automation typecheck and ... plugin-approvals typecheck — both green (check:test-typecheck: OK for each; plugin debt ledger unchanged at 8 files / 324 / 27 pinned).
• pnpm --filter @objectstack/service-automation test — Test Files 125 passed (125) · Tests 1486 passed (1486); pnpm --filter @objectstack/plugin-approvals test — Test Files 42 passed (42) · Tests 705 passed (705). Both packages' full suites; downstream importers owe no test (see consumers).
• New / changed pins: packages/services/service-automation/src/consumed-suspension-inspection.test.ts (10 tests: journal and durable witnesses, RUN_SUSPENDED, never-paused, snapshot-cleared-after-finish, the dropped snapshot from the stranding replica vs a fresh one, both store outages reject, barrel nameability + exhaustive switch); stranded-run-repairability.test.ts PIN 1 flipped + PIN 5 added; stranded-request-inspection.test.ts [Decision] inspectStrandedRequests now over-reports: it keys on status === 'failed' while the platform gained an authoritative strand discriminator — a cascade-failed run the engine calls NOT stranded is reported as one #15358 block (10 tests).
• Reverse verification (committed state, plugin repro via dist): PIN 1 with the pre-B′ expectation ['failed', 'failed'] re-applied → Tests 1 failed | 4 passed (5), AssertionError: expected [ [ …(2) ], …(1) ] to deeply equal …; restored with git checkout HEAD -- …, git hash-object = HEAD blob 613c8f6b… both sides, git diff HEAD --stat empty.
• Ablation A — naive durable-only read (hot journal ignored in resolveConsumedSuspensionWitnesses): on-disk grep -c original line 1→0, marker 0→1; pnpm --filter @objectstack/service-automation build exit 0; ablation-dist-preflight "marker present in 2 built files"; engine pins Tests 2 failed | 8 passed (the journal pin and the "stranding replica still answers repairable from its hot copy" pin — the ruling's stop condition, caught). The plugin repro stayed green under this mutation by construction (its in-memory store row carries the snapshot), which is why the engine-side pins exist.
• Ablation B — the member reads a held snapshot as absent (the service-automation: a throw between journalConsumedSuspension and the status: 'stranded' stamp makes a REPAIRABLE strand report repairable: false — the operator is told not to attempt a repair that works #15555 inversion, in the engine): marker a globalThis property so esbuild cannot fold it (a first attempt with a string-literal comparison was constant-folded out of dist and its reading discarded, as was an earlier non-compiling attempt); preflight "marker present in 2 built files"; engine pins Tests 3 failed | 7 passed; plugin Tests 2 failed | 35 passed — PIN 1 and PIN 5 red.
• Restore leg for both: git checkout HEAD -- engine.ts, blob b00f251d… = HEAD, whole-tree git status --porcelain empty, rebuild, preflight --absent "marker absent from all 6 built files", engine 10/10 and plugin 37/37 green.
• Derived gates: node scripts/pm/dispatch-gates.mjs --commands (no paths; merge-base self-derived, identical list pre- and post-merge) → 59 commands, all exit 0 after the packages closure was built; --ran → "59 derived famil(ies) accounted for — 59 run, 0 NOT-MEASURED". Three of them (check:dual-build-cjs-loads, check:i18n, check:type-check-debt) answered PREREQUISITE NOT MET (exit 3) before the closure build and green after it — not counted as red. pnpm check:error-code-casing (not derived; a new reason literal) green.
• pnpm lint (repo-level eslint) not run locally — CI's Lint & Repo Gates.

Consumers of the changed exports (import edges, with a positive control)

Import edges of @objectstack/plugin-approvals outside the package (git grep "from '@objectstack/plugin-approvals" over packages/**, examples/**, apps/**): exactly one — examples/app-showcase/test/approval-resume-relation-expand.test.ts:52 imports ApprovalsServicePlugin (the positive control). Zero import StrandedRunState, ApprovalResumeSurface or StrandedApprovalRequest; the remaining mentions are prose (a spec TSDoc, a CHANGELOG line, and automation-result-status.pin.test.ts asserting the docblock names StrandedRunState). The service-automation barrel addition is purely additive. ../objectui is not checked out in this container and was not measured.

Changeset

Judged against AGENTS.md's changeset rule: both packages publish, both diffs change published behaviour and published types → .changeset/stranded-run-state-discriminator.md, minor for each (additive members; the ruling names @objectstack/plugin-approvals minor). skip-changeset does not apply.

验收备注

• Commit history: two wip: commits were pushed before the coordinator asked for real messages; rewriting pushed commits needs a force-push, which this lane forbids, so they stand (ruled). This PR title and body carry the real message; the prose patch commit 42ce7bf4d carries a real one.
• noted, not filed: packages/spec/src/contracts/automation-service.ts:345 TSDoc says StrandedRunState is 'missing' | 'failed' — now stale prose; the ruling forbids a spec change in this PR, and it is a docs nit, not a defect.
• noted, not filed: stranded-run-repairability.test.ts PIN 3 pins that getRun carries neither discriminator field — under B′ that is now the intended contract (wire untouched), so the pin's role flipped from "measurement" to "guard"; its docblock says so.
• noted, not filed: inspectConsumedSuspension does not judge the restoring / resuming instant-safety guards (documented); a caller acting on repairable: true still goes through the restore verb, which does.
• Contract review tier: CONTRACT_REVIEW_TIER read from scripts/pm/dispatch-gates.mjs = claude-fable-5-1. Clause-②: yes — needs:contract-review on issue and PR.

Attribution: authored in Claude Code session session_012zTkyNHJ7TkuN2oXtP5x37.